GitLab CI Syntax and Variables Summary

TLDR

• The core configuration file for GitLab CI is .gitlab-ci.yml, which defines the execution logic of the Pipeline.
• It is recommended to prioritize rules over the legacy only/except to achieve more precise execution control.
• Use the ${VARIABLE_NAME} format for variable references to avoid confusion with subsequent text.
• workflow:rules can be used to control the trigger conditions for the entire Pipeline (e.g., executing only on specific branches or merge requests).
• The needs keyword can bypass Stage order restrictions, allowing a Job to execute immediately after its dependent Job completes.
• Effectively utilizing artifacts and cache can efficiently pass files and accelerate the execution of subsequent Jobs.

---

Basic Structure and Flow Control

The GitLab CI Pipeline is defined by .gitlab-ci.yml. For easier maintenance, it is recommended to split large configurations into multiple files (e.g., .gitlab-ci-deploy.yml) and include them using include.

Stages and Jobs

• Stages: Define the execution order. Jobs within the same Stage run in parallel, and all must succeed before moving to the next stage.
• Jobs: The smallest unit of actual execution. It is recommended to use an "action-object-environment" naming pattern (e.g., deploy-staging).

Rules and Workflow

• Rules: Define the execution conditions for a Job. When a rule matches, the when keyword determines whether to execute.
• Workflow: Controls the creation conditions for the entire Pipeline. If all rules evaluate to when: never, the entire Pipeline will not execute.

TIP

The official recommendation is to use rules instead of only/except, as the former supports more complex logical judgments, for example:

rules:
  - if: $CI_COMMIT_BRANCH == "main"
    when: always
  - when: never

---

Resource Management and Optimization

Cache and Artifacts

• Cache: Used to store files across Jobs (e.g., node_modules/) to accelerate subsequent builds. It is recommended to use ${CI_COMMIT_REF_SLUG} as the key.
• Artifacts: Used to store products generated by a Job (e.g., compiled binaries), which can be downloaded by subsequent Jobs.

Needs

If you want a Job to execute as soon as its specific dependent Job finishes, without waiting for the entire Stage to complete, you can use needs:

job2:
  stage: test
  needs:
    - job1
  script:
    - echo "This Job executes immediately after job1 completes"

---

Variable Usage Recommendations

In GitLab CI, variables can be defined globally or specific to a Job.

• Referencing: It is recommended to always use ${VARIABLE_NAME}. When a variable is followed immediately by other characters, this format clearly defines the scope of the name, preventing parsing errors.
• Naming Conventions: It is recommended to use all uppercase letters separated by underscores, such as DOCKER_IMAGE_NAME.

---

Predefined Variables Reference

GitLab CI provides a rich set of predefined variables. Common categories are listed below for reference:

Commit-related Variables

Variable	Description
CI_COMMIT_SHA	The commit revision for the project build.
CI_COMMIT_REF_NAME	The current branch or tag name.
CI_COMMIT_SHORT_SHA	The first eight characters of CI_COMMIT_SHA.

Job and Pipeline-related Variables

Variable	Description
CI_JOB_ID	The unique internal ID of the Job.
CI_PIPELINE_ID	The instance-level unique ID of the Pipeline.
CI_PIPELINE_SOURCE	The trigger source of the Pipeline (e.g., push, merge_request_event).

Project and Environment Variables

Variable	Description
CI_PROJECT_PATH	The namespace including the project name.
CI_PROJECT_URL	The HTTP(S) URL of the project.
CI_ENVIRONMENT_NAME	The environment name of the current Job.

WARNING

If you need to display double curly braces (e.g., in certain script templates), please ensure they are placed within an independent code block to avoid Vue compilation errors.

---

Change Log

• 2025-04-07 Initial documentation created.